OpenEuphoria

Documentation writing guideline:

Routines should be written so the "dot notation pre-processor" can make sense of the routine.

sequence str = "hello" 
 
-- ** Bad ** 
puts(1, str ) 
 
-- ** Good ** 
puts( str, 1 ) 
 
--> ** since ** 
puts(str)  --> makes sense 
str.puts() --> makes sense 
str.puts(1) --> makes sense 
 

Some features are suggested so that the intermediate text file is easy to parse. Then any desired look can be created by running a simple parsing utility.

• the description is one line that should read as if the identifier is the first word in the sentence. ** user routines do not need a "Description:" header
  • <built-in> routines do require a "Description:" header
• parameter names in a routine should be descriptive
• Parameters: header only needs to be followed by numbered description of parameters (since other information can be parsed out of the signature)
• Returns: must allow various return formats like integer, sequence
• New technical words are in bold followed "by a quoted definition."
• Examples should be self contained. It should be possible to copy and paste the example into the WEE editor and have the example execute. (Therefore must have all include files, all variables declared, ...)
• expected output in an example can be a comment line such as --> 0 for failure
• See Also: header, the items can be separated by just a blank space

A sample documented routine could look like:

--** 
-- checks whether two objects can perform a sequence operation together. 
-- Parameters: 
-- # one of the objects to test for compatible shape 
-- # the other object 
-- Returns: 
-- integer 
-- * 1 ; possible operation between ##a## and ##b## 
-- * 0 ; fails 
-- Comments: 
-- The **shape** of an object "considers length, branches, and length of branches." 
-- Shapes are **compatible** if "it is possible to perform an operation on every element." 
-- Note: 
-- An ##atom## is always compatible with a ##sequence## of any shape. 
-- Example 1: 
-- <eucode> 
-- 
--      include std/sequence.e 
--      integer i 
-- 
-- i = binop_ok({1,2,3},{4,5}) 
-- ? i 
-- --> 0 
-- 
-- i = binop_ok({1,2,3},4) 
-- ? i 
-- --> 1 
-- 
-- i = binop_ok({1,2,3},{4,{5,6},7}) 
-- ? i 
-- --> 1 
-- </eucode> 
-- See Also: 
-- [[:series]] 
 
public function binop_ok(object a, object b) 
	if atom(a) or atom(b) then 
		return 1 
	end if 
 
	if length(a) != length(b) then 
		return 0 
	end if 
 
	for i = 1 to length(a) do 
		if not binop_ok(a[i], b[i]) then 
			return 0 
		end if 
	end for 
 
	return 1 
end function 

The "look" of the resulting documentation can vary. It all depends on an intermediate parsing program.

EXAMPLE ONE

First Signature Style

which may produce documentation that looks like

binop_ok

checks whether two objects can perform a sequence operation together.

include function2.e 
public 
function binop_ok( 
                   object a, 
                   object b 
                 ) 

Returns:

Comments:

The shape of an object "considers length, branches, and length of branches." Shapes are compatible if "it is possible to perform an operation on every element."

Note:

An atom is always compatible with a sequence of any shape.

Example 1:

 
     include std/sequence.e 
     integer i 
 
i = binop_ok({1,2,3},{4,5}) 
? i 
--> 0 
 
i = binop_ok({1,2,3},4) 
? i 
--> 1 
 
i = binop_ok({1,2,3},{4,{5,6},7}) 
? i 
--> 1 

See Also:

| series |

EXAMPLE TWO

Alternative Signature Style

binop_ok

checks whether two objects can perform a sequence operation together.

function binop_ok(object a,object b)

Returns:

EXAMPLE THREE

Alternative Signature Style

binop_ok

checks whether two objects can perform a sequence operation together.

function  
binop_ok (  
          object a,   -- first object for comparison 
          object b     -- second object for comparison   
         ) 

Returns: